<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" "http://www.w3.org/TR/html4/loose.dtd">
<html>
<head>
<meta http-equiv="Content-Type" content="text/html; charset=UTF-8">
<title>Simple IRC Server</title>
</head>
<body>

 <center><h2>Simple IRC Server</h2></center>
 <center>v. 0.5.2</center>
 <center>2012-03-29</center>
 

 <p>Основной целью разработки является реализация протокола
  обмена сообщениями между клиентом и сервером в соответствии со
  спецификацией RFC2812 с использованием платформы программирования 
  Java SE.
 
 <h3>Содержание</h3>
 <ol>
  <li><a href="#usage">Использование</a></li>
  <li><a href="#configuration">Файл конфигурации</a></li>
  <li><a href="#realization">Реализация</a></li>
  <li><a href="#load_limitations">Ограничения по нагрузке</a></li>
  <li><a href="#source">Исходный текст</a></li>
  <li><a href="#binary">Исполняемый модуль</a></li>
  <li><a href="#archives">Состав архива</a></li>
  <li><a href="#versions">Версии</a></li>
  <li><a href="#developer">Разработчик</a></li>
 </ol>
 <ol>

  <h3>
   <li><a id="usage">Использование</a></li>
  </h3>
  <p>В качестве исполняемого модуля используется файл sis.jar, 
   находящийся в архиве. Для выполнения программы, необходимо, чтобы на 
   компьютере была развернута среда выполнения программ Java JRE версии 
   не ниже чем v1.6 и был установлен достаточный объем оперативной 
   памяти. Должно быть зарезервировано место для файла журналирования и 
   файла-протокола клиентских сообщений.
   
  <p><b>Для выполнения программы необходимо, что бы она имела доступ к 
  <a href="#configuration">файлу конфигурации</a> и для виртуальной 
  машины java был указан ключ -Xms с параметром не меньшим чем 32m.</b>
   
  <p>По умолчанию, программа ищет файл конфигурации с именем 
  "IrcServerConfig.xml в текущем директории, там же будет размещать
  журнальный файл с именем "IrcServerLog.xml" и файл-протокол с именем  
  "IrcServerTranscript.txt".
  
  <p>Информация с заданной степенью детализации о работе программы
   выводится в журнальный файл.
     
  <p>Запуск программы может производится из командной строки. При запуске,
  можно использовать следующие ключи:
  <ul>
   <li>-c <config file> - указание файла конфигурации;</li>
   <li>-h - вывод краткой справки;</li>
   <li>-l <logging file> - указание журнального файла;</li>
   <li>-V - вывод версии программы.</li>
  </ul>
  
  <p>Во время нормального завершения, программа передает
   операционной системе следующие коды завершения:
  <ul>
   <li>отсутствие ошибок: 0;</li>
   <li>обнаружена ошибка в командной строке: 1;</li>
   <li>неудача запуска компонентов программы или ошибка в файле
    конфигурации: 2.</li>
  </ul>

  <p>В среде Linux запуск может быть произведен следующим образом:
  <pre>java -Xms64m -jar sis.jar -c IrcServerConfig.xml -l IrcServerLog.xml &</pre>

  <p>В среде MS Windows программу можно запустить вот так:
  <pre>javaw -Xms64m -jar sis.jar -c IrcServerConfig.xml -l IrcServerLog.xml</pre>

  <p>Приведенные команды запуска можно использовать при небольшом
   количестве клиентов (до 500 подключений), если количество клиентов
   может быть больше, то необходимо увеличить объем доступной для java
   VM памяти с помощью ключа -Xmx. Можно использовать следующие варианты
   запуска:
  <p>Linux:
  <pre>java -Xms64m -Xmx1024m -jar sis.jar -c IrcServerConfig.xml -l IrcServerLog.xml &</pre>

  <p>MS Windows:
  <pre>javaw -Xms64m -Xmx1024m -jar sis.jar -c IrcServerConfig.xml -l IrcServerLog.xml</pre>

  <h4>Формат файла-протокола сообщений клиентов</h4>
  <p>Сообщения клиентов, которые будут переданы на исполнение,
   сохраняются в файле-протоколе. Каждое сообщение вместе со служебной
   информацией занимает одну строку. Служебная информация, в виде
   цепочек символов, размещается в начале строки и разделяется
   пробелами. Предоставляются следующие данные:
  <ol>
   <li>Время регистрации сообщения (UNIX epoch) с точностью до
    милисекунды в виде целого десятичного числа.</li>
   <li>Порядковый номер сообщения в виде целого десятичного числа.
    Используется сквозная нумерация всех поступающих сообщений.</li>
   <li>Сетевой идентификатор отправителя в виде "/IP-адрес:номер
    сокета".</li>
   <li>Никнэйм отправителя.</li>
   <li>Либо три тире "---", либо число "424". Символы "---"
    указывают на то, что сообщение было передано на анализ и исполнение.
    Число "424" указывает на то, что из-за высокой нагрузки на сервер,
    сообщение не было обработано и клиенту был передан цифровой ответ
    ERR_FILEERROR.</li>
  </ol>

  <p>После последнего элемента служебной информациии выводится
   пробел, затем сообщение клиента.
  <p>В сообщениях клиентов, содержащих команду IRC "OPER", параметры
   команды &lt;username&gt; и &lt;password&gt; в файл-протокол не
   выводятся.
  <p>Пустые сообщения и сообщения длиной более 510 символов не
   обрабатываются и не выводятся в файл-протокол.
   
  <h4>Автоматическая генерация никнэймов</h4>
  <p>При установлении связи, клиенту присваивается уникальный
   никнэйм, который можно использовать в дальнейших обменах. Он ничем не
   отличается от обычных никнэймов и его можно заменить с помощью
   команды IRC "NICK". Этот никнэйм является одним из вариантов
   семизначного 36-ричного представления порядкового номера клиента.
   Используется сквозная нумерация клиентов, отсчет ведется от первого
   подключения после запуска сервера.
   
  <h4>Функционирование в режиме высокой степени нагрузки на сервер</h4>
  <p>При диагностировании высокой степени нагрузки на сервер или при
    недостатке доступной памяти, программа прекращает регистрацию вновь
    подключающихся клиентов и закрывает их сетевые соединения.
    
  <p>При функционирование в этом режиме, клиенты делятся на две 
    категории: операторы и обычные клиенты. Команды операторов 
    продолжают выполняются в соответствии со спецификациями. Набор 
    команд обычных клиентов ограничивается следующими командами: PING; 
    PONG; ADMIN; TIME; OPER. Эти команды исполняются в соответствии со 
    спецификациями, на все остальные команды возвращается цифровой ответ 
    ERR_FILEERROR "424 &lt;nickname&gt; :File error doing 
    &lt;command&gt; on SERVER", где &lt;nickname&gt; - это никнэйм 
    клиента, а &lt;command&gt; - это команда IRC.
   
   
  <h3><li><a id="configuration">Файл конфигурации</a></li></h3>
  <p>В этом файле должна быть указана следующая информация о сервере и 
  администраторе сервера:
  <ol>
   <li>Имя, фамилия и email администратора сервера.</li>
   <li>Адрес расположения сервера IRC.</li>
   <li>Наименование и адрес организации, которой принадлежит сервер
    IRC.</li>
   <li>Краткая информация о сервере.</li>
  </ol>

  <p>В файле конфигурации можно указать следующие параметры IRC
   сервера:
  <ol>
   <li>Уровень сохраняемых сообщений журналирующей подсистемы.</li>
   <li>TimeZone сервера.</li>
   <li>IP - адрес интерфейса, на котором будет открыт порт.</li>
   <li>Номер порта для входящих соединений.</li>
   <li>Кодировку сообщений для этого интерфейса.</li>
   <li>Путь к файлу-протоколу сообщений клиентов.</li>
   <li>Количество ротаций файлов-протоколов.</li>
   <li>Максимальная длина файла-протокола клиентских сообщений, по
    достижению которой производится ротация файлов-протоколов.</li>
   <li>Пары параметров "логин" "пароль" для операторов IRC.</li>
  </ol>  
  
  <p>Для файла конфигурации используется следующая DTD.
  <pre>

  &lt;?xml version="1.0" encoding="UTF-8"?&gt;
  &lt;!-- DTD --&gt;
  &lt;!DOCTYPE CONFIG
      [
          &lt;!ELEMENT CONFIG (ADMIN, SERVER?, INTERFACE?, TRANSCRIPT?, 
           OPERATOR*)&gt;
              &lt;!ELEMENT ADMIN (#PCDATA)&gt;
              &lt;!ATTLIST ADMIN 
                  name CDATA #REQUIRED 
                  location CDATA #REQUIRED
                  location2 CDATA #REQUIRED
                  email CDATA #REQURED
                  info CDATA #REQURED
              &gt;
              &lt;!ELEMENT SERVER (#PCDATA)&gt;
              &lt;!ATTLIST SERVER
                  debuglevel CDATA 
                  timezone CDATA
                  motd CDATA
              &gt;
              &lt;!ELEMENT INTERFACE (#PCDATA)&gt;
              &lt;!ATTLIST INTERFACE
                 iface CDATA 
                 port CDATA
                 charset CDATA
              &gt;
              &lt;!ELEMENT TRANSCRIP (#PCDATA)&gt;
              &lt;!ATTLIST TRANSCRIP 
                  transcript CDATA
                  rotate CDATA
                  length CDATA
             &gt;
              &lt;!ELEMENT OPERATOR (#PCDATA)&gt;
              &lt;!ATTLIST OPERATOR 
                 username CDATA #REQUIRED 
                 password CDATA #REQUIRED
             &gt;
      ]
  &gt;
</pre>


  <p>Ниже приведены описания элементов и атрибутов:
  <ol>
   <li>Все атрибуты должны быть строками в кодировке US-ASCII.</li>
   <li>Атрибуты элемента "ADMIN":
    <ul>
     <li>"name", с помощью этого атрибута указываются имя и фамилия
      администратора сервера;</li>
     <li>"location", с помощью этого атрибута указывается адрес
      расположения сервера IRC;</li>
     <li>"location2", с помощью этого атрибута указывается
      наименование и адрес организации, которой принадлежит сервер IRC;</li>
     <li>"email", с помощью этого атрибута указывается адрес
      электронной почты администратора сервера;</li>
     <li>"info", с помощью этого атрибута кратко характризуется
      назначение сервера IRC.</li>
    </ul>В файле конфигурации должны быть определены все атрибуты этого 
    элемента. Их значения используются при выполнении команды IRC ADMIN.
   </li>
   <li>Атрибуты элемента "SERVER":
    <ul>
     <li>"debuglevel", с помощью этого атрибута указывается уровень
      журналируемых сообщений. Эти уровни определены в классе
      java.util.logging.Level. Допустимо использовать следующие уровни:
      <ul>
       <li>SEVERE (высший уровень);</li>
       <li>WARNING;</li>
       <li>INFO;</li>
       <li>CONFIG;</li>
       <li>FINE;</li>
       <li>FINER;</li>
       <li>FINEST (низший уровень);</li>
       <li>OFF - отключение журналирования;</li>
       <li>ALL - регистрация всех сообщений;</li>
      </ul> с уменьшением уровня увеличивается количество и разнообразие
      журналируемых сообщений. По умолчанию, используется значение
      WARNING;
     </li>
     <li>"timezone", с помощью этого атрибута задается часовой пояс
      сервера. Допустимые значения определены в классе
      java.util.TimeZone. По умолчанию используется значение "GMT".</li>
     <li>"motd", с помощью этого атрибута указывается 
      путь к файлу MOTD. По умолчанию будет использован файл 
      "IrcServerMotd.txt" в текущем каталоге;</li>
    </ul>
   <li>Атрибуты элемента "INTERFACE":
    <ul>
     <li>"iface", с помощью этого атрибута, в нотации IPv4,
      задается IP-адрес интерфейса, который будет использован для
      входящих сетевых подключения. В случае указания пустой строки,
      сервер будет использовать все доступные сетевые интерфейсы. По
      умолчанию значение атрибута равно пустой строке;</li>
     <li>"port", с помощью этого атрибута задается номер порта
      интерфейса, который будет использован для входящих сетевых
      подключений. Атрибут должен быть целым десятичным числом в
      диапазоне 0 - 65535. По умолчанию в качестве номера порта
      используется номер 6667;</li>
     <li>"charset", с помощью этого атрибута задается кодировка
      входящих сообщений. Значения этого атрибута определяется в классе
      java.nio.charset.Charset. Допустимо использовать следующие
      кодировки:
      <ul>
       <li>US-ASCII;</li>
       <li>ISO-8859-1;</li>
       <li>UTF-8;</li>
       <li>UTF-16BE;</li>
       <li>UTF-16LE;</li>
       <li>UTF-16.</li>
      </ul> по умолчанию в качестве кодировки интерфейса используется
      кодировка "UTF-8".
     </li>
    </ul>
   <li>Атрибуты элемента "TRANSCRIPT":
    <ul>
     <li>"transcript", с помощью этого атрибута указывается путь к
      файлу с протоколом клиентских сообщений. По умолчанию будет
      использован файл "IrcServerTranscript.txt" в текущем каталоге;</li>
     <li>"rotate", с помощью этого атрибута указывается количество
      сохраняемых экземпляров файлов-протоколов клиентских сообщений. По
      умолчанию это количество равно 5;</li>
     <li>"length", с помощью этого атрибута указывается
      максимальная длина в байтах файлов-протоколов клиентских
      сообщений. К числу может быть добавлен суффикс - одна из латинских
      букв "K" или "M", для задания множителей 1024 и 1048576
      соответственно. По умолчанию эта длина ограничена 100K байт.</li>
    </ul>
   <li>Атрибуты элемента "OPERATOR": "username" и "password".
    Значениями этих атрибутов должны быть значения, которые будут
    использоваться как параметры &lt;username&gt; и &lt;password&gt;
    команды IRC "OPER". Максимальное количество этих элементов
    ограничено 100 единицам.</li>
   </ol>
   <p>Ниже приведено примерное содержание файла конфигурации.
   <pre>
&lt;?xml version="1.0" encoding="UTF-8"?&gt;
&lt;!-- File Name: IrcServerConfig.xml --&gt;
&lt;CONFIG&gt;
        &lt;ADMIN name="Adminname Adminsurname" 
            location="25, Serverstreet, Servercity, Servercountry" 
            location2="Organizationname, 25, Organizationstreet, Organizationcity, Organizationcountry"  
            email="ircAdmin@dom.ain" 
            info="Experimental IRC server."&gt;
        &lt;/ADMIN&gt;
        &lt;SERVER 
            timezone="GMT+0400" 
            debuglevel="WARNING"
            motd="IrcServerMotd.txt"&gt;
        &lt;/SERVER&gt;
        &lt;INTERFACE  
            port="6667" 
            charset="UTF-8"&gt;
        &lt;/INTERFACE&gt;
        &lt;TRANSCRIPT 
            transcript="IrcServerTranscript.txt" 
            length="100K" 
            rotate="5"&gt;
            &lt;/TRANSCRIPT&gt;
        &lt;OPERATOR 
            username="operatorname1" password="operatorpassword1"&gt;
        &lt;/OPERATOR&gt;
        &lt;OPERATOR 
            username="operatorname2" password="operatorpassword2"&gt;
        &lt;/OPERATOR&gt;
&lt;/CONFIG&gt;
  </pre>

   <h3>
    <li><a id="realization">Реализация</a></li>
   </h3>
   <ol>
    <li>Реализованные команды (RFC2812): NICK; USER; OPER; MODE;
     QUIT; JOIN; PART; TOPIC; NAMES; LIST; INVITE; KICK; PRIVMSG;
     NOTICE; MOTD; LUSERS; VERSION; STATS; LINKS; TIME; ADMIN; INFO;
     WHO; WHOIS; WHOWAS; KILL; PING; PONG; ERROR; AWAY; REHASH; DIE;
     RESTART; WALLOPS; USERHOST; ISON.</li>
    <li>Команды с ограниченной реализацией: MODE (User mode message
     и Channel mode message) для вывода параметров ключа, необходимо
     использовать символ ключа без префикса; STATS - не реализовано
     вычисление некоторых статистических показателей.</li>
    <li>Команды с нереализованным функционалом: PASS; SERVICE;
     SQUIT; CONNECT; TRACE; SQUERY; SUMMON.</li>
    <li>Длина никнэйма ограничена 15 символами.</li>
    <li>Длина имени канала ограничена 50 символами.</li>
    <li>Поддерживается возможность обмена сообщений с
     использованием одной из следующих кодировок - US-ASCII, ISO-8859-1,
     UTF-8, UTF-16BE, UTF-16LE, UTF-16.</li>
    <li>Цифровой ответ "005" используется в варианте ISUPPORT.</li>
    <li>Цифровой ответ "424" "ERR_FILEERROR" дополнен
     дополнительными вариантами использования.</li>
    <li>Не реализована возможность подключение сервисов (RFC2810
     2.2.2 Service Clients).</li>
    <li>Не реализован межсерверный протокол обмена сообщениями 
    (RFC2813).</li>
    <li>Поддерживаются только локальные каналы.</li>
    <li>Сетевые идентификаторы не используются.</li>
    <li>Адресация сообщений поддерживается только для никнэймов
     пользователей и названий каналов. Адресация с помощью сетевых
     идентификаторов не поддерживается.</li>
    <li>Максимальное количество элементов списка для команд с
     адресаций равно 5.</li>
    <li>Отсутствует режим "локальный оператор".</li>
    <li>Максимальная допустимая скорость ввода сообщений клиентом -
     одно сообщение в 2 секунды.</li>
    <li>Максимальная средняя скорость передачи сообщений в канал -
     10 сообщений в 10 секунд. Эта средняя скорость вычисляется как
     суммарная средняя скорость передачи сообщений в канал всех членов
     канала.</li>
   </ol>
  <h3>
   <li><a id="load_limitations">Ограничения по нагрузке</a></li>
  </h3>
  <ol>
   <li>Максимальное количество сетевых подключений - 4000.</li>
   <li>Максимальное количество каналов - 2000.</li>
   <li>Максимальное количество участников обмена сообщениями канала
    - 1000.</li>
   <li>Максимальное количество каналов, к которым может подключится
    пользователь - 5.</li>
   <li>Максимальная средняя скорость ввода сообщений для одного
    пользователя - 1 сообщение в 2 секунды.</li>
   <li>Максимальная средняя скорость передачи сообщений в канал -
    10 сообщений в 10 секунд. Эта средняя скорость вычисляется как
    суммарная средняя скорость передачи сообщений в канал всех членов
    канала.</li>
  </ol>
   <h3>
    <li><a id="source">Исходный текст</a></li>
   </h3>

   <p>Архив с исходными текстами находится в файле sis-0-5-2.jar
   <p>Все классы находятся в "default" пакете. Модули компиляции
    размещены в различных каталогах так, что бы отражалось их
    функциональное назначение. Для сборки программы необходимо, либо
    указывать sourcepath для модулей, либо скопировать все модули
    компиляции в один каталог и производить сборку там. В архиве
    находится файл build.xml, который можно использовать при сборке с
    помощью Apache ant (версия не ниже чем 1.7). В этом файле
    (build.xml) определены следующие цели:
   <ol>
    <li>"compile" - компиляция модулей.</li>
    <li>"dist" - создание jar-файла из откомпилированных модулей.</li>
    <li>"run" - запуск на исполнение созданного jar-файла.</li>
    <li>"javadoc" - генерация javadoc.</li>
    <li>"clean build" - удаление откомпилированных модулей.</li>
    <li>"clean dist" - удаление jar-файла.</li>
    <li>"clean run" - удаление временного директория, в котором
     происходит запуск программы.</li>
    <li>"clean javadoc" - удаление javadoc.</li>
    <li>"clean all" - выполнение "clean build", "clean dist",
     "clean run", "clean javadoc" одной командой.</li>
   </ol>

   <h3>
    <li><a id="binary">Исполняемый модуль</a></li>
   </h3>

   <p>Исполняемый модуль находится в файле sis.jar.

   <h3>
    <li><a id="archives">Состав архива</a></li>
   </h3>

   <p>Программа в виде исходных текстов, исполняемого кода и
    описания распространяется на условиях LGPL v3 .
   <p>В состав архива входят следующие компоненты:
   <ol>
    <li>GNU Lesser General Public License Version 3, 29 June 2007:
     lgpl.txt</li>
    <li>Исходные тексты программы: sis-0-5-2.jar</li>
    <li>Исполняемый модуль: sis.jar</li>
     <li>Краткое описание: index.ru.html</li>
   </ol>
   <h3>
    <li><a id="versions">Версии</a></li>
   </h3>
   <p>v.0.5.2  от 2012-03-29: Добавлено указание пути к файлу MOTD в 
   файл конфигурации, изменен выходной текст команды INFO. 
   Размещение проекта по адресу: 
   <a href="http://code.google.com/p/simple-irc-server/">
   http://code.google.com/p/simple-irc-server/</a>
   
   <p>v.0.5.1 от 2012-03-20: Размещение архива по адресу: 
   <a href="http://sites.google.com/site/workpalace2012/">
   http://sites.google.com/site/workpalace2012/</a> 
   
   <h3>
    <li><a id="developer">Разработчик</a></li>
   </h3>
   <p>Николай Кирдин
   <p>email: nkirdin@gmail.com
      
  </ol>
  <p>&copy;Nikolay Kirdin, 2012
</body>
</html>